Docs
post https://gateway.iugu.com/api/v1/transactions/cancel/{payment_id}

Cancelar um pagamento

Cancela ou reembolsa um pagamento previamente capturado ou autorizado.

────────────────────────────────────────────────────────────────────────────────

CANCELAMENTO TOTAL:

Para cancelar o valor total, envie amount_cents com o valor total do pagamento. O parâmetro é obrigatório: se ausente, a resposta é 400 invalid_amount.

Se o pagamento já foi totalmente reembolsado, retorna 200 com o estado atual do pagamento, sem nova chamada ao adquirente.

────────────────────────────────────────────────────────────────────────────────

CANCELAMENTO PARCIAL:

É possível cancelar parcialmente um pagamento. A soma de todos os cancelamentos não pode exceder o valor original. Autorizações só podem ser canceladas com o valor total (cancelamento parcial não é permitido).

────────────────────────────────────────────────────────────────────────────────

RESTRIÇÕES:

  • Valores devem ser maiores que zero.
  • Prazo máximo de cancelamento configurável por workspace.
  • Limite de taxa (quando habilitado): máximo de 1 requisição por hora por payment_id.

────────────────────────────────────────────────────────────────────────────────

POLÍTICAS ESPECÍFICAS POR ADQUIRENTE:

  • Getnet: Cancelamento parcial no mesmo dia (D0) não é permitido
  • Outras restrições podem variar por adquirente (Cielo, Rede)

Sem ações implementadas definidas

Request

Path variables

payment_id

Required

Type: string

ID do pagamento a ser cancelado

Headers

Workspace-Id

Type: string

ID do workspace. Quando ausente, é usado o workspace padrão do Gateway.

Ex: 1D81KhKbYuVq9505Bz4Nk9

Body Required

Content Type: application/json

amount_cents

Required

Integer >= 1

Valor a ser reembolsado em centavos. Para cancelamento total, envie o valor total do pagamento.

Ex: 5000

account_info
Object

Dados da conta repassados à análise antifraude

Example
1
2
3
4
5
{
  "amount_cents": 5000,
  "account_info": {
  }
}

Response

200

Pagamento cancelado com sucesso (ou já totalmente reembolsado)

payment
Object

id
String

status
String
Enum: `authorized`, `charged`, `captured`, `partially_refunded`, `fully_refunded`, ``

Nulo quando nenhuma tentativa foi aprovada pelo adquirente

multi
Array of strings

success_ec
String

ID do estabelecimento que aprovou a transação

mcc
String

recurrent
Boolean

card_on_file
Boolean

tid
String

nsu
String

authorization_code
String

amount_cents
Integer

refunded_amount_cents
Integer

cnpj
String

workspace_id
String

account_id
String

invoice_id
String

`order_id` informado na criação do pagamento

client_ref
String

subscription_id
String

card_id
String

card_bin
String

card_last_four
String

currency
String

installments
Integer

soft_descriptor
String

created_at
String

updated_at
String

transactions
Array of objects

id
String

function
String
Enum: `authorization`, `charge`, `capture`, `cancel`

success
Boolean

tid
String

nsu
String

arp
String

acquirer
Object

payment_id
String

status_code
String

acquirer_mac_code
String

status_description
String

request_status_code
String

request_status_description
String

lr
Object

Código de retorno unificado da tentativa. Vale tanto para a recusa do adquirente quanto para a do próprio Gateway, e é o campo que substituirá `acquirer.status_code`.

code
String

Código de retorno. Da adquirente quando `source` é `acquirer`; do Gateway (`TOK01`, `MCC01`, `DEC01`…) quando é `gateway`. Vem nulo com `source` igual a `acquirer` nas transações anteriores à introdução do campo, em que o código está apenas em `acquirer.status_code`.

source
String
Enum: `acquirer`, `gateway`

Origem do código. `gateway` significa que a transação foi recusada antes de chegar ao adquirente.

card_id
String

card_bin
String

card_last_four
String

card_on_file
Boolean

transaction_token_type
String
Enum: `open`, `acquirer_token`, `network_token`, ``

Tipo de dado de cartão enviado ao adquirente

amount_cents
Integer

ec_group
Object

id
String

name
String

commercial_enterprise
Object

id
String

name
String

number
String

acquirer
String

mcc
Object

id
String

code
String

description
String

created_at
String

anti_fraud
Array of objects

Análises antifraude do pagamento, da mais recente para a mais antiga

id
String

payment_id
String

provider
String

Ex: feedzai

provider_id
String

decision
String

omniscore
String

created_at
String

Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
{
  "payment": {
    "id": "<ID>",
    "status": "<STATUS>",
    "multi": [
      "<MULTI>"
    ],
    "success_ec": "<SUCCESS_EC>",
    "mcc": "<MCC>",
    "recurrent": "<RECURRENT>",
    "card_on_file": "<CARD_ON_FILE>",
    "tid": "<TID>",
    "nsu": "<NSU>",
    "authorization_code": "<AUTHORIZATION_CODE>",
    "amount_cents": "<AMOUNT_CENTS>",
    "refunded_amount_cents": "<REFUNDED_AMOUNT_CENTS>",
    "cnpj": "<CNPJ>",
    "workspace_id": "<WORKSPACE_ID>",
    "account_id": "<ACCOUNT_ID>",
    "invoice_id": "<INVOICE_ID>",
    "client_ref": "<CLIENT_REF>",
    "subscription_id": "<SUBSCRIPTION_ID>",
    "card_id": "<CARD_ID>",
    "card_bin": "<CARD_BIN>",
    "card_last_four": "<CARD_LAST_FOUR>",
    "currency": "<CURRENCY>",
    "installments": "<INSTALLMENTS>",
    "soft_descriptor": "<SOFT_DESCRIPTOR>",
    "created_at": "<CREATED_AT>",
    "updated_at": "<UPDATED_AT>",
    "transactions": [
      {
        "id": "<ID>",
        "function": "<FUNCTION>",
        "success": "<SUCCESS>",
        "tid": "<TID>",
        "nsu": "<NSU>",
        "arp": "<ARP>",
        "acquirer": {
          "payment_id": "<PAYMENT_ID>",
          "status_code": "<STATUS_CODE>",
          "acquirer_mac_code": "<ACQUIRER_MAC_CODE>",
          "status_description": "<STATUS_DESCRIPTION>",
          "request_status_code": "<REQUEST_STATUS_CODE>",
          "request_status_description": "<REQUEST_STATUS_DESCRIPTION>"
        },
        "lr": {
          "code": "<CODE>",
          "source": "<SOURCE>"
        },
        "card_id": "<CARD_ID>",
        "card_bin": "<CARD_BIN>",
        "card_last_four": "<CARD_LAST_FOUR>",
        "card_on_file": "<CARD_ON_FILE>",
        "transaction_token_type": "<TRANSACTION_TOKEN_TYPE>",
        "amount_cents": "<AMOUNT_CENTS>",
        "ec_group": {
          "id": "<ID>",
          "name": "<NAME>"
        },
        "commercial_enterprise": {
          "id": "<ID>",
          "name": "<NAME>",
          "number": "<NUMBER>",
          "acquirer": "<ACQUIRER>",
          "mcc": {
            "id": "<ID>",
            "code": "<CODE>",
            "description": "<DESCRIPTION>"
          }
        },
        "created_at": "<CREATED_AT>"
      }
    ],
    "anti_fraud": [
      {
        "id": "<ID>",
        "payment_id": "<PAYMENT_ID>",
        "provider": "feedzai",
        "provider_id": "<PROVIDER_ID>",
        "decision": "<DECISION>",
        "omniscore": "<OMNISCORE>",
        "created_at": "<CREATED_AT>"
      }
    ]
  }
}

400

Requisição inválida. Possíveis causas: - `invalid_parameter_error`: parâmetro com tipo inválido ou não documentado - `invalid_amount`: `amount_cents` ausente, zero ou negativo - `payment_cannot_be_canceled`: o adquirente (Cielo) informou que o pagamento não está em estado que permite cancelamento - `bad_request`: o adquirente rejeitou o cancelamento (`details` traz a resposta do adquirente)

Example
1
"<SCHEMA>"

401

Não autorizado - Token de autenticação inválido ou ausente

message
String
Enum: `Requires authentication`, `Bad credentials`

Example
1
2
3
{
  "message": "<MESSAGE>"
}

404

Recurso não encontrado. Possíveis causas: - `payment_not_found`: Pagamento com o ID informado não existe - `payment_transaction_not_found`: Transação cancelável do pagamento não encontrada - `commercial_enterprise_not_found`: Estabelecimento comercial da transação não encontrado

error
String

Tipo do erro

Ex: payment_not_found

service
String

Nome do serviço que gerou o erro

Ex: Acquirers::CancelService

details
Object

Detalhes adicionais (estrutura varia por tipo de erro)

Example
1
2
3
4
5
6
{
  "error": "payment_not_found",
  "service": "Acquirers::CancelService",
  "details": {
  }
}

409

`payment_processing_in_progress`: outra requisição para o mesmo pagamento está em processamento; tente novamente

error
String

Tipo do erro

Ex: payment_not_found

service
String

Nome do serviço que gerou o erro

Ex: Acquirers::CancelService

details
Object

Detalhes adicionais (estrutura varia por tipo de erro)

Example
1
2
3
4
5
6
{
  "error": "payment_not_found",
  "service": "Acquirers::CancelService",
  "details": {
  }
}

422

Erro de validação ou política. Possíveis causas: - `amount_not_permitted`: Valor solicitado excede o disponível para cancelamento - `authorization_cannot_be_partially_canceled`: Autorizações só podem ser canceladas totalmente - `cancellation_deadline_exceeded`: Prazo máximo para cancelamento foi excedido - `deny_getnet_D0_partial_refund`: Getnet não permite cancelamento parcial no mesmo dia (D0) - `deny_rede_D0_partial_refund`: Rede não permite cancelamento parcial no mesmo dia (D0) - `deny_rede_elo_D0_refund`: Rede não permite cancelamento de transação Elo no mesmo dia (D0), nem total nem parcial - `no_successful_transaction_to_cancel`: O pagamento não possui transação bem-sucedida cancelável - `cannot_create_payment_transaction`: Falha ao registrar a transação de cancelamento

error
String

Tipo do erro

Ex: payment_not_found

service
String

Nome do serviço que gerou o erro

Ex: Acquirers::CancelService

details
Object

Detalhes adicionais (estrutura varia por tipo de erro)

Example
1
2
3
4
5
6
{
  "error": "payment_not_found",
  "service": "Acquirers::CancelService",
  "details": {
  }
}

429

Limite de taxa excedido Quando o limite está habilitado, apenas 1 requisição de cancelamento por hora é permitida para cada payment_id. A cota é consumida por qualquer requisição autenticada, inclusive as que retornam erro.

error
String
Enum: `rate_limit_exceeded`

message
String

Ex: Rate limit exceeded. Try again later.

Example
1
2
3
4
{
  "error": "<ERROR>",
  "message": "Rate limit exceeded. Try again later."
}

500

Erro interno do servidor. Possíveis causas: - `payment_cancelation_error`: Erro inesperado ao aplicar as políticas de cancelamento - Outros erros inesperados durante o processamento. Entre em contato com o suporte se o problema persistir.

error
String

Tipo do erro

Ex: payment_not_found

service
String

Nome do serviço que gerou o erro

Ex: Acquirers::CancelService

details
Object

Detalhes adicionais (estrutura varia por tipo de erro)

Example
1
2
3
4
5
6
{
  "error": "payment_not_found",
  "service": "Acquirers::CancelService",
  "details": {
  }
}